.TH nsfm 1  "March 21, 2011" "version 0.1" "USER COMMANDS"

.SH NAME
nsfm
\-- a (new) simple file manager

.SH SYNOPSIS
nsfm [ <filename> | <directory> ]
.PP
nsfm -l <filename>
.PP
nsfm -x <filename>
.PP
nsfm -h

.SH DESCRIPTION
.PP
nsfm is a curses-based, terminal-oriented file and directory browser.  Its main
strength is fast, keyboard-driven navigation between directories and to files
within directories.  nsfm incorporates a facility for selecting and launching
commands based upon the file type of the currently-selected file.

nsfm implements several modes.  In normal mode (known as 'listing/ls' mode) the
main panel displays the output of the "ls -l" command in the current working
directory.  Other modes provide mechanisms for selecting directories from a
number of sources, or for selecting commands for execution.

In all cases, the primary mode of navigation and/or selection is incremental
search.  The alphanumerical keys plus the ".", "*" and "&" keys are used to
build up a filter.  Only those entries matching the current filter are
displayed.  All other entries are supressed.  Generally, just a few keystrokes
are required to select the file or directory required.

The matching rules for filters are as follows.  Alphanumerical terms and "."
match themselves.  The "*" term matches any sequence of characters.  Matching
is not tied to the beginning or end of the entry.  Therefore, a filter such as
"X*Y" matches any entry which the shell glob "*X*Y*" would match.  For example,
the filter "st*io" would match a file named "instructions.pdf", as would the
filter ".pdf".

Additionally, the filter term "&" resets the matching process to the beginning
of the entry, and matching continues from there.  For example, the filter
".pdf&st*io" also matches the entry "instructions.pdf".  In general, a filter
such as "A*B&X*Y" matches any entry that both the glob "*A*B*" and the glob
"*X*Y" would match.  This feature can be particularly useful when used with
marks (see below).

If the filter contains no capital letters, then matching is case insensitive.
Otherwise, matching is case sensitive.

In all modes, the currently-selected item is the one at the top of the list.
Its name is also displayed in the bottom panel, lest there be any doubt.

.SH KEY BINDINGS

For information on key bindings, see the output of "nsfm -h".

.SH MODES

nsfm implements several modes.  The mode name is always displayed in the top
right-hand corner of the window.

The modes are as follows:

.TP
listing/ls (this is the main or normal mode)
The main panel contains the output of the "ls -l" command in the
current working directory.  Any filter is applied only to that part of the
listing which is a file or directory name (it does not apply to file
perimisions, file owner, etc).

.TP
listing/dirs
The main panel again contains the output of the "ls -l" command in the
current working directory.  In this case, however, only directories and soft
links to directories are included in the listing, files and other types of
entries are excluded.  This can be convenient for navigation between
directories.

.TP
commands
The main panel contains a list of commands selected based on the file type of
the currently selected file.  Any filter is applied only to that part of each
command which is not the file name (because the file name is usually the
same for all of the commands, so it is unlikely to be the basis of a useful
filter).

Three mechanisms are used to identify commands appropriate to a particular
file: its suffix, its MIME type as reported by the Python 'mimetypes' module,
and its MIME type as reported by the 'file -bi' command.

.TP
history/dirs
The main panel contains a list of previously-visited directories.  Any filter
is applied to the entire path displayed.

The history of visited directories is retained between sessions, although
filters and positions within directories are not.

.TP
cd path/dirs
The main panel contains a list of directories found on the current CDPATH.  Any
filter is applied only to the basename component of directories' paths.

This mode is mainly uselful if the CDPATH environment variable is exported.  If
the CDPATH environment variable is not defined, then the default path for this
mode includes only the user's home directory.

.TP
tabs
The main panel contains a list directories visited in the current session,
together with the filter and position associated with each entry. 

.TP
marks
The main panel contains a list of marks, each mark being a name, a directory and a
filter.  Selecting a mark opens the given directory with the given filter.

Marks are similar to marks in the 'vim' text editor.  The key sequence "@k"
creates a mark named "k", and the key sequence "'k" jumps to an existing mark
named "k".

Valid mark names are all of the alphanumerical characters.

Marks are retained between sessions.

.SH CONFIGURATION

All configuration is via the nsfm configuration file.  The output of "nsfm -h"
includes a list of locations in which nsfm searches for its configuration file.
The first such file found is selected.  nsfm will start if it cannot find this
file, but no commands will be available for execution (in 'commands' mode).

Within the configuration file, the "#" character indicates a comment.

The configuration file contains file type specifications (based on suffixes and
MIME types) and corresponding commands.

See the sample configuration file circulated with this distribution for more
information.

.SH BUGS
There are probably many bugs.  Please let me know if/when you find one.  Bug
fixes are particularly appreciated.

.SH FILES
.TP
nsfm.rc
(or possibly '.nsfm.rc') configuration file (see 'nsfm -h' for a list of
possibly locations)
.TP
~/.nsfm.log
log file
.TP
~/.nsfm.help
help file, output of 'nsfm -h'
.TP
~/.nsfm.visited
history file, for 'history' mode
.TP
~/.nsfm.marks
marks file, for 'marks' mode
.SH EXIT STATUS
nsfm usually yields an exit status of 0, but may yield something else if bad
things happen.

Once nsfm is initialised, all error messages are directed to "~/.nsfm.log".

.SH AUTHOR
Stephen Blott (smblott AND-THAT'S-AT gmail.com)

